home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / glimpse-2.1 / agrep / README < prev    next >
Text File  |  1995-05-16  |  6KB  |  135 lines
  1. /* Copyright (c) 1994 Sun Wu, Udi Manber, Burra Gopal.  All Rights Reserved. */
  2. This is version 2.04 of agrep - a new tool for fast 
  3. text searching allowing errors.
  4. agrep is similar to egrep (or grep or fgrep), but it is much more general
  5. (and usually faster).
  6. The main changes from version 1.1 are 1) incorporating Boyer-Moore
  7. type filtering to speed up search considerably, 2) allowing multi patterns 
  8. via the -f option; this is similar to fgrep, but from our experience 
  9. agrep is much faster, 3) searching for "best match" without having to
  10. specify the number of errors allowed, and 4) ascii is no longer required.
  11. Several more options were added.
  12.  
  13. To compile, simply run make in the agrep directory after untar'ing
  14. the tar file (tar -xf agrep-2.04.tar will do it).
  15.  
  16. The three most significant features of agrep that are not supported by
  17. the grep family are 
  18. 1) the ability to search for approximate patterns;
  19.     for example, "agrep -2 homogenos foo" will find homogeneous as well 
  20.     as any other word that can be obtained from homogenos with at most 
  21.     2 substitutions, insertions, or deletions.
  22.     "agrep -B homogenos foo" will generate a message of the form
  23.     best match has 2 errors, there are 5 matches, output them? (y/n)
  24. 2) agrep is record oriented rather than just line oriented;  a record
  25.     is by default a line, but it can be user defined;
  26.     for example, "agrep -d '^From ' 'pizza' mbox"
  27.     outputs all mail messages that contain the keyword "pizza".
  28.     Another example:  "agrep -d '$$' pattern foo" will output all
  29.     paragraphs (separated by an empty line) that contain pattern.
  30. 3) multiple patterns with AND (or OR) logic queries.   
  31.     For example, "agrep -d '^From ' 'burger,pizza' mbox" 
  32.     outputs all mail messages containing at least one of the 
  33.     two keywords (, stands for OR).
  34.     "agrep -d '^From ' 'good;pizza' mbox" outputs all mail messages
  35.     containing both keywords.
  36.  
  37. Putting these options together one can ask queries like
  38.  
  39. agrep -d '$$' -2 '<CACM>;TheAuthor;Curriculum;<198[5-9]>' bib
  40.  
  41. which outputs all paragraphs referencing articles in CACM between 
  42. 1985 and 1989 by TheAuthor dealing with curriculum.  
  43. Two errors are allowed, but they cannot be in either CACM or the year 
  44. (the <> brackets forbid errors in the pattern between them).  
  45.  
  46. Other features include searching for regular expressions (with or
  47. without errors), unlimited wild cards, limiting the errors to only 
  48. insertions or only substitutions or any combination, 
  49. allowing each deletion, for example, to be counted as, say, 
  50. 2 substitutions or 3 insertions, restricting parts of the query 
  51. to be exact and parts to be approximate, and many more.
  52.  
  53. agrep is available by anonymous ftp from cs.arizona.edu (IP 192.12.69.5)
  54. as agrep/agrep-2.04.tar.Z (or in uncompressed form as agrep/agrep-2.04.tar).
  55. The tar file contains the source code (in C), man pages (agrep.1),
  56. and two additional files, agrep.algorithms and agrep.chronicle,
  57. giving more information.
  58. The agrep directory also includes two postscript files: 
  59. agrep.ps.1 is a technical report from June 1991 
  60. describing the design and implementation of agrep;
  61. agrep.ps.2 is a copy of the paper as appeared in the 1992
  62. Winter USENIX conference.
  63.  
  64. Please mail bug reports (or any other comments) 
  65. to sw@cs.arizona.edu or to udi@cs.arizona.edu.
  66.  
  67. We would appreciate if users notify us (at the address above)
  68. of any extensions, improvements, or interesting uses of this software.
  69.  
  70. January 17, 1992
  71.  
  72.  
  73. BUGS_fixed/option_update
  74.  
  75. 1. remove multiple definitions of some global variables.
  76. 2. fix a bug in -G option.
  77. 3. fix a bug in -w option.
  78. January 23, 1992
  79.  
  80. 4. fix a bug in pipeline input.
  81. 5. make the definition of word-delimiter consistant.
  82. March 16, 1992
  83.  
  84. 6. add option '-y' which, if specified with -B option, will always
  85. output the best-matches without a prompt.
  86. April 10, 1992
  87.  
  88. 7. fix a bug regarding exit status.
  89. April 15, 1992
  90.  
  91. -------------------------------------------------------------------------------
  92. REVISIONS TO AGREP, FALL '93
  93.  
  94. 8. Options can now be specified in a single group of characters after one '-'.
  95.    - Sept 3rd 1993
  96.  
  97. 9. Made agrep callable as a library routine from a separate function. The
  98.    interface is: memagrep(argc, argv, searchbufferlen, searchbuffer),
  99.    the pattern to be searched for and the options being specified EXACTLY as
  100.    if they are being specified on the command line. The only difference is
  101.    that instead of the file-names to look at, the user should specify a buffer
  102.    and its length. Sample user programs are in ../user directory.
  103.    
  104.    In memagrep(), there are TWO peculiarities:
  105.    1. Peculiarity #1 -- at the end of the buffer, the user must have N bytes
  106.       of valid virtual memory, where N is the length of the pattern to be
  107.       searched. This space is used by agrep to speed up the checking of the
  108.       termination condition. Its contents are restored before memagrep()
  109.       returns -- however, some space must be there... else you'll get SIGSEGV.
  110.       I might trap segv and do a longjmp, but that'll be in a new version!
  111.    2. The search buffer must begin with a newline so that it is easy for
  112.       agrep to output matched lines. This also avoids some copying.
  113.    Ofcourse, if we copied the user's search buffer into another buffer which
  114.    meets both the above conditions, memagrep() will no longer be fast -- and
  115.    speed is the primary goal.
  116.  
  117.    - Sept 27th 1993
  118.  
  119. 10. Added some filter-programs to make agrep search thru compressed files.
  120.    Also added some features in the Makefile which allows the user to build
  121.    an agrep with a dummyfilter so that agrep remains independent of tcompress.
  122.    The definitions needed in agrep to interface with tcompress are in defs.h
  123.  
  124.    - Nov 10th 1993
  125.  
  126. 11. Added a library interface for searching thru a specified set of files,
  127.     fileagrep(), which is similar to memagrep(). This is used by glimpse.
  128.     Had to modify some other things and fix some bugs (see CHANGES).
  129.  
  130.    - Dec 1993 (coding), Jan 1993 (debugging).
  131. -------------------------------------------------------------------------------
  132.  
  133. CODING NOTE: sgrep.c and newmgrep.c use a similar while(fill_buf) loop
  134. with start and end, while others use loops with an internal variable i.
  135.